cisco.aci.aci_rest 模块 – 直接访问 Cisco APIC REST API

注意

此模块是 cisco.aci 集合 (版本 2.10.1) 的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用： ansible-galaxy collection install cisco.aci。您需要进一步的要求才能使用此模块，请参阅 要求 以了解详细信息。

要在 playbook 中使用它，请指定： cisco.aci.aci_rest。

概要

• 通过直接访问 Cisco APIC REST API 来实现 Cisco ACI 结构的管理。

• 由于 APIC 的幂等性，此模块是幂等的，并报告更改。

要求

执行此模块的主机需要以下要求。

• lxml (当使用 XML 有效负载时)

• xmljson >= 0.1.8 (当使用 XML 有效负载时)

• python 2.7+ (当使用 xmljson 时)

参数

参数	注释
annotation 字符串	用户定义的字符串，用于注释对象。 如果在任务中未指定该值，则将改用环境变量 ACI_ANNOTATION 的值。 如果在任务中未指定该值，并且环境变量 ACI_ANNOTATION 也未指定，则将使用默认值。 默认值： "orchestrator:ansible"
certificate_name 别名：cert_name 字符串	附加到用于基于签名的身份验证的 APIC AAA 用户的 X.509 证书名称。 如果提供了 private_key 文件名，则此默认值为 private_key 的基本名称，不带扩展名。 如果为 private_key 提供了 PEM 格式的内容，则此默认值为 username 值。 如果在任务中未指定该值，则将改用环境变量 ACI_CERTIFICATE_NAME 的值。
content 任何	当代替 src 使用时，直接设置 API 请求的有效负载。 这可能方便模板化简单请求。 对于任何复杂的情况，请使用 template 查找插件（请参阅示例）或使用参数 src 的 template 模块。
host 别名：hostname 字符串	Ansible 控制主机可解析的 APIC 的 IP 地址或主机名。 如果在任务中未指定该值，则将改用环境变量 ACI_HOST 的值。
method 别名：action 字符串	请求的 HTTP 方法。 使用 delete 通常用于删除对象。 使用 get 通常用于查询对象。 使用 post 通常用于修改对象。 选项 "delete" "get" ← (默认) "post"
output_level 字符串	影响此 ACI 模块的输出。 normal 表示标准输出，包括 current 字典 info 添加信息性输出，包括 previous、proposed 和 sent 字典 debug 添加调试输出，包括 filter_string、method、response、status 和 url 信息 如果在任务中未指定该值，则将改用环境变量 ACI_OUTPUT_LEVEL 的值。 选项 "debug" "info" "normal" ← (默认)
output_path 字符串	用于转储模块生成的 ACI JSON 配置对象的文件路径。 如果任务中未指定该值，则将使用环境变量 ACI_OUTPUT_PATH 的值。
密码 字符串	用于身份验证的密码。 此选项与 private_key 互斥。如果也提供了 private_key，则将使用它。 如果任务中未指定该值，则将使用环境变量 ACI_PASSWORD 或 ANSIBLE_NET_PASSWORD 的值。
path 别名: uri string / required	用于执行 API 调用的 URI。 必须以 .xml 或 .json 结尾。
端口 整数	用于 REST 连接的端口号。 默认值取决于参数 use_ssl。 如果任务中未指定该值，则将使用环境变量 ACI_PORT 的值。
private_key 别名: cert_key 字符串	用于基于签名身份验证的 PEM 格式私钥文件或私钥内容。 此值还会影响所使用的默认 certificate_name。 此选项与 password 互斥。如果也提供了 password，则将忽略它。 如果任务中未指定该值，则将使用环境变量 ACI_PRIVATE_KEY 或 ANSIBLE_NET_SSH_KEYFILE 的值。
rsp_subtree_preserve 布尔值	保留所提供路径的响应。 选项 false ← (默认) true
src 别名: config_file 路径	包含发送到 ACI 架构的 HTTP 请求正文的绝对路径的文件名。 如果需要模板化的有效负载，请将 content 参数与 template 查找插件一起使用，或者使用 template。
suppress_previous 别名: no_previous, ignore_previous 布尔值	如果为 true，则在向 APIC 发送 POST 更新之前，不会发送 GET 请求来检查之前的状态。 如果任务中未指定该值，则将使用环境变量 ACI_SUPPRESS_PREVIOUS 的值。 默认值为 false。 警告 - 这会导致先前的返回值为空。 不会检查对象的先前状态，并且 POST 更新将包含所有属性。 选项 false true
suppress_verification 别名: no_verification, no_verify, suppress_verify, ignore_verify, ignore_verification 布尔值	如果为 true，则在向 APIC 发送 POST 更新后，不会发送验证 GET 请求。 如果任务中未指定该值，则将使用环境变量 ACI_SUPPRESS_VERIFICATION 的值。 默认值为 false。 警告 - 这会导致当前返回值设置为建议值。 包括默认值在内的当前对象在单个任务中将无法验证。 选项 false true
超时 整数	套接字级别的超时时间，以秒为单位。 如果任务中未指定该值，则将使用环境变量 ACI_TIMEOUT 的值。 默认值为 30。
use_proxy 布尔值	如果为 false，则即使在目标主机上的环境变量中定义了代理，也不会使用代理。 如果任务中未指定该值，则将使用环境变量 ACI_USE_PROXY 的值。 默认值为 true。 选项 false true
use_ssl 布尔值	如果为 false，则将使用 HTTP 连接而不是默认的 HTTPS 连接。 如果任务中未指定该值，则将使用环境变量 ACI_USE_SSL 的值。 当连接为本地连接时，默认值为 true。 选项 false true
username 别名: user 字符串	用于身份验证的用户名。 如果任务中未指定该值，则将使用环境变量 ACI_USERNAME 或 ANSIBLE_NET_USERNAME 的值。 默认值为 admin。
validate_certs 布尔值	如果为 false，则不会验证 SSL 证书。 仅当在个人控制的站点上使用自签名证书时，才应将其设置为 false。 如果任务中未指定该值，则将使用环境变量 ACI_VALIDATE_CERTS 的值。 默认值为 true。 选项 false true

注意

注意

• 已知某些有效负载不是幂等的，因此在构造有效负载时要小心，例如使用 status="created" 会导致幂等性问题，请改用 status="modified"。有关更多信息，请参阅 :ref:`ACI 文档 `。

• 已知某些有效负载（和使用的路径）在发生更改时会报告没有发生更改。这是一个已知的 APIC 问题，并且已报告给供应商。存在此问题的解决方法。有关更多信息，请参阅 :ref:`ACI 文档 `。

• XML 有效负载需要 lxml 和 xmljson Python 库。对于 JSON 有效负载，则不需要任何特殊操作。

• 如果您没有任何属性，则可能需要添加带有空字典“{}”作为值的“attributes”键，因为 APIC 期望该条目位于任何子项之前。

• 直接在 c(src) 或 content 中设置的注释将优先于 annotation 参数。

另请参阅

另请参阅

cisco.aci.aci_tenant

管理租户 (fv:Tenant)。

Cisco APIC REST API 配置指南

有关 APIC REST API 的更多信息。

Cisco ACI 指南

有关如何使用 Ansible 管理 ACI 基础架构的详细信息。

开发 Cisco ACI 模块

有关如何编写自己的 Cisco ACI 模块以进行贡献的详细指南。

示例

- name: Add a tenant using certificate authentication
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    method: post
    path: /api/mo/uni.xml
    src: /home/cisco/ansible/aci/configs/aci_config.xml
  delegate_to: localhost

- name: Add a tenant from a templated payload file from templates/
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    method: post
    path: /api/mo/uni.xml
    content: "{{ lookup('template', 'aci/tenant.xml.j2') }}"
  delegate_to: localhost

- name: Add a tenant using inline YAML
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    validate_certs: false
    path: /api/mo/uni.json
    method: post
    content:
      fvTenant:
        attributes:
          name: Sales
          descr: Sales department
  delegate_to: localhost

- name: Add a tenant using a JSON string
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    validate_certs: false
    path: /api/mo/uni.json
    method: post
    content:
      {
        "fvTenant": {
          "attributes": {
            "name": "Sales",
            "descr": "Sales department"
          }
        }
      }
  delegate_to: localhost

- name: Add a tenant using an XML string
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/{{ aci_username }}.key
    validate_certs: false
    path: /api/mo/uni.xml
    method: post
    content: '<fvTenant name="Sales" descr="Sales departement"/>'
  delegate_to: localhost

- name: Get tenants using password authentication
  cisco.aci.aci_rest:
    host: apic
    username: admin
    password: SomeSecretPassword
    method: get
    path: /api/node/class/fvTenant.json
  delegate_to: localhost
  register: query_result

- name: Configure contracts
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    method: post
    path: /api/mo/uni.xml
    src: /home/cisco/ansible/aci/configs/contract_config.xml
  delegate_to: localhost

- name: Register leaves and spines
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    validate_certs: false
    method: post
    path: /api/mo/uni/controller/nodeidentpol.xml
    content:
      <fabricNodeIdentPol>
        <fabricNodeIdentP name="{{ item.name }}" nodeId="{{ item.nodeid }}" status="{{ item.status }}" serial="{{ item.serial }}"/>
      </fabricNodeIdentPol>
  with_items:
    - '{{ apic_leavesspines }}'
  delegate_to: localhost

- name: Wait for all controllers to become ready
  cisco.aci.aci_rest:
    host: apic
    username: admin
    private_key: pki/admin.key
    validate_certs: false
    path: /api/node/class/topSystem.json?query-target-filter=eq(topSystem.role,"controller")
  register: apics
  until: "'totalCount' in apics and apics.totalCount|int >= groups['apic']|count"
  retries: 120
  delay: 30
  delegate_to: localhost
  run_once: true

返回值

此处记录了常见的返回值 here，以下是此模块特有的字段

键	描述
error_code 整数	REST ACI 返回代码，有助于在失败时进行故障排除 返回：始终 示例： 122
error_text 字符串	REST ACI 描述性文本，有助于在失败时进行故障排除 返回：始终 示例： "unknown managed object class foo"
imdata 字符串	APIC REST 返回的转换输出（注册此项以进行后处理） 返回：始终 示例： "[{'error': {'attributes': {'code': '122', 'text': 'unknown managed object class foo'}}}]"
payload 字符串	发送到 APIC REST API 的（模板化）有效负载 (xml 或 json) 返回：始终 示例： "<foo bar=\"boo\"/>"
raw 字符串	APIC REST API 返回的原始输出 (xml 或 json) 返回：解析错误 示例： "<?xml version=\"1.0\" encoding=\"UTF-8\"?><imdata totalCount=\"1\"><error code=\"122\" text=\"unknown managed object class foo\"/></imdata>"
response 字符串	HTTP 响应字符串 返回：始终 示例： "HTTP Error 400: Bad Request"
status 整数	HTTP 状态代码 返回：始终 示例： 400
totalCount 字符串	imdata 数组中的项目数 返回：始终 示例： "0"
url 字符串	用于 APIC REST 调用的 URL 返回：成功 示例： "https://1.2.3.4/api/mo/uni/tn-[Dag].json?rsp-subtree=modified"

作者

• Dag Wieers (@dagwieers)

• Cindy Zhao (@cizhao)

• Samita Bhattacharjee (@samitab)

集合链接

• 问题跟踪器
• 仓库（源代码）