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 的值。
password 字符串	用于身份验证的密码。 此选项与 private_key 互斥。如果也提供了 private_key，则将使用它。 如果任务中未指定值，则使用环境变量 ACI_PASSWORD 或 ANSIBLE_NET_PASSWORD 的值。
path 别名：uri 字符串 / 必填	用于执行 API 调用的 URI。 必须以 .xml 或 .json 结尾。
port 整数	用于 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 lookup 插件一起使用，或使用 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
timeout 整数	以秒为单位的套接字级别超时。 如果任务中未指定值，则使用环境变量 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 文档 <aci_guide_known_issues>`。

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

• 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

返回值

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

键	描述
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 (@cizhao)

• Samita Bhattacharjee (@samitab)

资源链接

• 问题追踪器
• 代码仓库 (源代码)