Руководство по 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 серии с 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 в Ansible Galaxy.

Если вы хотите узнать, как создавать собственные модули 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 API APIC.

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

Сбор фактов

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

 - 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. (По умолчанию admin)

password

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

private_key

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

certificate_name

Имя сертификата в веб-интерфейсе ACI. По умолчанию это либо значение username, либо имя файла 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 по ACI и Ansible

Аутентификация ACI

Аутентификация по паролю

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

username: admin
password: my-password

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

Функция «Vault» в Ansible позволяет хранить конфиденциальные данные, такие как пароли или ключи, в зашифрованных файлах, а не в виде открытого текста в ваших playbook или ролях. Эти файлы 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
....

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

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 !

При запуске playbook используйте «–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.

Например, если вы хотите убедиться, что определённый Tenant существует в 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

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

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

• Коллекция ACI в Ansible Galaxy
• Руководство по конфигурации API REST APIC – подробное руководство по проектированию и использованию API REST APIC, включая многочисленные примеры
• Справочник по модели информации управления APIC – полное описание модели объекта APIC
• Практические занятия Cisco DevNet по 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 сообщает о состоянии «fully-fit».

- 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. Один из способов избежать этого — использовать YAML или XML-форматированный payload, которые легче правильно создать и изменить позднее.

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

Хотя спецификация JSON допускает неупорядоченные элементы, API REST APIC требует, чтобы элемент 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 является оболочкой вокруг 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.

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

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

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

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