我们希望听到您的意见！帮助我们深入了解 Ansible 生态系统现状。
参加 2024 年 Ansible 项目调查

Ansible Tower API 入门

来源

Ansible Tower API 入门

欢迎阅读“入门”系列的另一篇文章。API（应用程序编程接口），或者像我一样称之为自动化信息的神奇世界，可以以多种方式使用。在本入门文章中，我们将讨论 Red Hat Ansible Tower 的 API 以及如何使用它提取信息以在您的 playbook 和其他工具中使用。

这篇博文的灵感来自于 David Federlein 开发一个新的 Ansible Tower 演示和演示文稿。我将参考该代码库，您可以在本文中参考它。请注意，此演示利用了 Vagrant 和 VirtualBox，因此如果您想自己搭建演示环境，则需要安装这些应用程序。

Ansible Tower 的 API

Ansible Tower 的 API 完全可浏览。您可以通过在浏览器中输入以下内容导航到您的实例的 REST API：http://<Tower 服务器名称>/api/v2。到达那里后，您可以点击任何列出的链接并查看在 Ansible Tower 中为该特定属性加载的当前对象。您可以在 Ansible Tower 的 UI 中执行的所有操作都可以通过 API 执行；您还可以使用它查看从凭据到用户的所有内容。正如我们将在下一节中回顾的那样，您可以手动发布到 API 或通过 playbook 进行调用。

发布到 API

您可以通过多种不同的方式向 API 发出调用，但今天我们将重点介绍两种最基本的方法

  1. 从 Ansible Tower 的 REST API 接口手动发布
  2. 从 playbook 发布

我在这里所说的“基本”是指这些方法仅通过 Ansible Tower 完成。如大多数人可能知道的那样，您可以使用 Ansible Tower 中的信息与其他应用程序一起做一些非常棒的事情。

我们不仅能够通过这些方法配置和修改 Ansible Tower，而且还将演示您可以通过 API 调用启动作业。这将允许与企业基础设施的其他方面更紧密地集成，并能够运行 Red Hat Ansible Engine 工作负载，同时仍受围绕这些资源和作业模板配置的基于角色的访问控制的约束。

手动发布

首先，发布到 API 最简单（尽管不是最快或最自动化的）方法是从 API 接口进行。在这里，您可以选择一个要发布到的对象。每个对象在页面底部都有一个模板，显示发布中可以包含的字段。

例如，假设您想通过 API 将项目添加到 Ansible Tower 实例中。您只需导航到 Ansible Tower 的 API 屏幕 (https://<towerip>/api/v2) 选择项目 URL (/api/v2/projects/)，然后向下滚动到底部。那里将显示内容，如下所示

{
    "name": "",
    "description": "",
    "local_path": "",
    "scm_type": "",
    "scm_url": "",
    "scm_branch": "",
    "scm_clean": false,
    "scm_delete_on_update": false,
    "credential": null,
    "timeout": 0,
    "organization": null,
    "scm_update_on_launch": false,
    "scm_update_cache_timeout": 0
}

获得该内容后，使用您环境中的相关信息填充引号。将其粘贴到您的字段中后，点击 POST。如果发布成功，您可以在 Ansible Tower UI 和 API 中查看该项目。

如果失败，您将收到错误请求的通知。修复错误的方法将在其下方用引号显示。例如，如果您正在创建用户并且未为该用户输入密码，则它将失败并返回以下错误

{
    "password": [
        "This field may not be blank."
    ]
}

如果您在向 API 发布时遇到任何问题（如上述错误），则位于 UI 右上角 GET 旁边的 OPTIONS 按钮可以提供很大的帮助。OPTIONS 按钮描述了您希望发布到的特定对象或端点的 POST、PUT 和 PATCH 的可接受值。

修复内容字段中的错误后，再次点击“发布”，并注意该对象现已成功添加到 Ansible Tower 中。

通过 Playbook 发布

发布到 Ansible Tower API 的另一种方法是通过 playbook。我在文章开头链接的 GitHub 存储库在整个安装后 playbook 中都执行此操作。安装后执行的几乎所有操作都是通过 API 完成的。

要查看它的实际操作，让我们同步您刚刚添加到实例中的该项目。这需要您事先了解 Ansible Playbook 的构建知识。如果您需要帮助或想复习您的 playbook 知识，可以访问我们的文档。

启动作业同步的 playbook 利用了 Ansible 中的URI 模块。此模块用于与 Web 服务（例如 Ansible Tower API）交互。此确切的 playbook 可以在我上面链接的代码库中的 /roles/tower/main.yml 中找到。

- name: kick off project sync
  uri:
    url:  https://localhost/api/v1/projects/7/update/
    method: POST
    user: admin
    password: "{{ towerpass }}"
    validate_certs: False
    status_code:
      - 200
      - 201
      - 202
  when: response.status == 201

在此 playbook 任务中，我们告诉 Ansible 导航到项目的 API URL。在本例中，它是 https://localhost/api/v2/projects/7/update/。请注意，项目在更新前有一个数字。项目在 Ansible Tower 中根据其进入 Ansible Tower 的时间分配一个数字。此数字只能通过导航到项目的 API 接口 https://<您的 IP 地址>/api/v2/projects/ 找到。到达那里后，您需要找到要同步的项目，然后发布到该项目编号的更新端点。示例对项目编号 7 执行更新。

找到要更新的正确项目后，您需要发布到更新端点。在本例中，由于我们正在更新项目 7，因此端点为 https://localhost/api/v1/projects/7/update/。

为了使此发布与 URI 模块一起成功工作，您还需要向 API 传递您用来登录 Tower 的用户凭据。在本例中，我们使用默认的管理员用户。您可以使用任何具有足够权限执行此类发布的用户。

启动作业

现在，标题可能看起来有点模棱两可。“Jake，在 Ansible Tower 中启动作业并不难。”这是正确的，但对于此示例，我们将从 playbook 任务中在 Ansible Tower 中启动作业，这是您可以通过向 API 发出调用来执行的另一件事。我将要参考的具体示例可以在 vagrant-common 角色 (/roles/vagrant-common/main.yml) 中找到。

现在，一旦您拿出您的眼镜，我正在缩小的任务在下面的示例中找到

name: kick off the provisioning job template
  shell:  "curl -f -H 'Content-Type: application/json' -XPOST --user
admin:{{ towerpass }}
https://172.16.2.42/api/v2/job_templates/8/launch/ --insecure"
  when: inventory_hostname == 'demovm4'

乍一看，您会看到正在使用的 shell 模块，它向特定的 https 端点运行 curl 命令。碰巧的是，此 https 端点是用于启动特定作业模板的 API 端点。

该特定作业模板在 Ansible Tower 中分配了一个编号。为了不必深入 API 查找您的特定作业模板端点，一个快速简便的方法是导航到您要通过 API 启动的作业模板。到达那里后，查看 URL，分配给它的编号将显示在那里。

找到正确的作业模板后，https 端点将类似于 api/v2/job_templates/8/launch/。使用 curl 命令中的 -XPOST 命中该端点，您应该就可以运行了。

由以下机构提供支持