Руководство по 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) Fabric включает коммутаторы Cisco Nexus 9000 Series с APIC для работы в режиме ACI leaf/spine. Эти коммутаторы образуют сеть «fat-tree», соединяя каждый лист с каждым позвонком; все остальные устройства подключаются к узлам-листьям. APIC управляет ACI-матрицей.

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

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

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

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

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

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

• Adam Raffe: Изучение ACI
• Luca Relandini: ACI для чайников
• Cisco DevNet Learning Labs об ACI

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

Модули Ansible ACI предоставляют удобный интерфейс для управления вашей средой ACI с помощью 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

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

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

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

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

     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_password: my-password
     ansible_connection: local

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

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

    state: query
  register: all_tenants

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

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

host

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

port

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

username

Имя пользователя для входа в APIC.

password

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

private_key

Приватный ключ для входа в APIC с помощью аутентификации на основе подписи. Это может быть либо содержимое приватного ключа (включая заголовок/подпись), либо файл, содержащий содержимое ключа. Новое в версии 2.5

certificate_name

Имя сертификата в веб-интерфейсе ACI. По умолчанию это либо значение username, либо имя файла private_key.

timeout

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

use_proxy

Использовать системные настройки прокси.

use_ssl

Использовать HTTPS или HTTP для взаимодействия с APIC REST.

validate_certs

Проверять сертификат при использовании HTTPS.

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 позволяет хранить конфиденциальные данные, такие как пароли или ключи, в зашифрованных файлах, а не в виде открытого текста в ваших задачах или ролях. Эти файлы Vault можно затем распространять или размещать в системе управления версиями. Подробнее см. Использование Vault в задачах.

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

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

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

Аутентификация на основе подписи требует (самозаверяющего) сертификата 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 !

или вы можете использовать содержимое закрытого ключа:

 username: admin
 private_key: |
     -----BEGIN PRIVATE KEY-----
     <<your private key content>>
     -----END PRIVATE KEY-----
 certificate_name: admin  # This could be left out !

Использование Ansible Vault для шифрования закрытого ключа

Для начала зашифруйте закрытый ключ и задайте надежный пароль.

ansible-vault encrypt admin.key

Используйте текстовый редактор, чтобы открыть закрытый ключ. Теперь у вас есть зашифрованный сертификат.

$ANSIBLE_VAULT;1.1;AES256
56484318584354658465121889743213151843149454864654151618131547984132165489484654
45641818198456456489479874513215489484843614848456466655432455488484654848489498
....

Скопируйте и вставьте новый зашифрованный сертификат в вашу задачу как новую переменную.

private_key: !vault |
      $ANSIBLE_VAULT;1.1;AES256
      56484318584354658465121889743213151843149454864654151618131547984132165489484654
      45641818198456456489479874513215489484843614848456466655432455488484654848489498
      ....

Используйте новую переменную для private_key:

username: admin
private_key: "{{ private_key }}"
certificate_name: admin  # This could be left out !

При запуске задачи используйте «–ask-vault-pass» для расшифровки закрытого ключа.

ansible-playbook site.yaml --ask-vault-pass

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

• Подробную информацию об аутентификации на основе подписи можно найти на странице Cisco APIC Signature-Based Transactions.
• Дополнительную информацию о Ansible Vault можно найти на странице Ansible Vault.

Использование 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 запросы, но также принимает вложенный YAML-запрос (структурированный как JSON). XML-запрос требует использования пути, заканчивающегося .xml, в то время как JSON или YAML требуют, чтобы путь заканчивался .json.

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

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

XML (Родной ACI REST)

- 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 (Родной ACI REST)

- 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

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

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

• Документация модуля aci_rest
• Руководство по конфигурации APIC REST API – подробное руководство по разработке и использованию API REST APIC, включая многочисленные примеры
• Справочник по модели информации управления APIC – Полный справочник по модели объекта APIC
• Cisco DevNet Learning Labs об ACI и REST

Примеры работы

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

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

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

Вы можете использовать приведенную ниже задачу после начала построения 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 допускает неупорядоченные элементы, API REST APIC требует, чтобы элемент 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 является оболочкой вокруг API REST APIC. В результате любые проблемы, связанные с 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)

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

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

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

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

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