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

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

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

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

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

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

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

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

XML (Native 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 (Native 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 (Ansible-style 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

Задача 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_rest
• APIC REST API Configuration Guide – Подробное руководство по проектированию и использованию API REST APIC, включая многочисленные примеры
• APIC Management Information Model reference – Полное руководство по модели объектов APIC
• Cisco DevNet Learning Labs об ACI и REST

Примеры операционной работы

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

Свободно вносите свой вклад в добавление более полезных фрагментов.

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

Вы можете использовать задачу ниже после запуска ваших 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 не прошло валидацию для значения ‘Сеть «legacy»’

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

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

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

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

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