Руководство по 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 по ACI

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

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

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

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

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

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