跳至主要內容

精读笔记（RHCA 英文教材）· DO447 Chapter 11 Communicating with APIs using Ansible

大约 9 分钟

精读笔记（RHCA 英文教材）· DO447 Chapter 11 Communicating with APIs using Ansible

教材原文：RHCA 官方英文教材（教材第 401~444 页）（OCR 整书版已从本站移除，本页为章节精读） 关联知识：Ch10 SUMMARY 提到的“Tower REST API”在本章展开；uri 模块与 Ch4（过滤器/Jinja2）联动；Ch9（Job Template 是 API 操作对象）；本系列配套 00-RHCA教材精读-导航与学习法.md 章节结构：11.1 用 Tower API 启动作业（curl/playbook/Token 认证）→ 11.2 用 Ansible playbook 与任意 REST API 交互（uri 模块/响应处理/过滤器）→ Lab Communicating with APIs using Ansible（api-review）

Chapter Goal / Objectives（原文+译）

  • GOAL: Interact with REST APIs in Ansible Playbooks, and control Red Hat Ansible Tower using its REST API.（在 playbook 里与 REST API 交互，并用 REST API 控制 Tower）
  • OBJECTIVES：① 用 curl 及 Ansible playbook 访问 Tower API 控制 Tower；② 写 playbook 与 REST API 交互（从 Web 服务取信息、触发事件）。

11.1 Launching Jobs with the Ansible Tower API（用 Tower API 启动作业）

Tower REST API 基础（考点）

  • Tower 提供 REST API：让管理员/开发者越过 Web UI 用标准 HTTP 消息控制 Tower（自定义脚本/外部应用集成）。任何支持 HTTP 的语言/框架都能用。
  • 版本：API 在活跃开发中，部分 UI 功能可能 API 不可达；有 v1、v2 两个版本，v1 即将废弃，一律用 v2。
  • 端点示例：curl -X GET https://tower.lab.example.com/api/ -k 返回 JSON 入口；可浏览版 https://tower.lab.example.com/api/（点 /api/v2/ 浏览各资源）；常用资源：job_templates、jobs、inventories、credentials、projects、users、me、ping、unified_jobs、schedules、tokens 等。
  • JSON 可读性：json_pp（perl-JSON-PP 包）美化输出；图形浏览器点 ? 图标可看端点文档（讲师强调：多用这个文档资源）。
  • 分页（IMPORTANT）：API 响应可能分页——next 给出下一页 URI，为 null 则是末页；previous 同理（首页为 null）。
  • HTTP 语义：GET 取表示、POST 建/触发、PUT 整体改、DELETE 删、PATCH 局部改。

用 API 启动作业（考点：两段式 GET→POST）

  • Tower 3.2 起可按名称引用 Job Template（名称含空格需 %20 转义或用双引号 URL 编码；老 v1 API 只能用 ID）。
  • 先 GET 拿参数：curl -X GET .../api/v2/job_templates/"Demo Job Template"/launch/ -k -s | json_pp → 返回 launch 需要的默认值（inventory/credential/extra_vars 等）与各 ask_* 开关（如 ask_inventory_on_launch）。
  • 再 POST 启动：对同一 launch/ URI 发 POST → 返回新 job 的 JSON（关键字段：id、status: pending、url → /api/v2/jobs/72/）；用该 job id 的 GET 查状态/结果（含 playbook、finished、result_stdout 等）。
  • 按 ID 也可：.../job_templates/?name="..." 搜出 id 后 POST .../job_templates/6/launch/。
  • 认证：示例用 --user admin:redhat（Basic）；生产建议 token（见下）或 Vault 加密保管。

从 Ansible Playbook 启动作业（考点：uri 模块 + Vault）

  • 用 uri 模块访问 Tower API 可从 playbook 启动另一作业；该 playbook 也能挂在 Job Template 里由 Tower 跑（“作业里启动作业”）。
  • 示例要点（named URL + urlencode）：
    vars:
tower_user: admin
tower_pass: redhat
tower_host: demo.example.com
tower_job: Demo%20Job%20Template # 或 {{ 'Demo Job Template' | urlencode }}
tasks:
- name: Launch a new Job
uri:
url: "https://{{ tower_host }}/api/v2/job_templates/{{ tower_job }}/launch"
method: POST
validate_certs: no
return_content: yes
user: "{{ tower_user }}"
password: "{{ tower_pass }}"
force_basic_auth: yes
status_code: 201
  • 安全（考点）：明文用户名/密码不要提交到 SCM——用 ansible-vault encrypt 加密 playbook 或把秘密放变量文件再加密。
  • Vault Credential：Tower 要解密加密文件，需建 Vault Credential（TYPE=Vault；VAULT PASSWORD=加密密码；VAULT IDENTIFIER 可选，多密码加密才填），并把该凭据加到使用该 Project 的 Job Template；新版可用多个 Vault Credential 解密不同密码加密的文件。

Token 认证（考点：OAuth2 / PAT）

  • Tower 3.3+ API 用 OAuth2 提供 token 认证；带合法 token 的请求即通过认证。两类 token：Application Tokens（为常被多用户访问的客户端应用申请）与 Personal Access Tokens（PAT）（单用户，简单）。
  • 用法：先 POST 向 /api/v2/users/1/personal_tokens/ 申请 PAT（Basic 认证，201）→ register 响应；后续请求在 headers 带 Authorization: Bearer {{ token }}：
    - name: Get the token
uri:
url: "https://{{ tower_host }}/api/v2/users/1/personal_tokens/"
method: POST
user: "{{ tower_user }}"; password: "{{ tower_pass }}"
force_basic_auth: yes; status_code: 201
register: response
- name: Use the token to launch
uri:
url: "https://{{ tower_host }}/api/v2/job_templates/{{ template_name | urlencode }}/launch/"
method: POST
headers:
Authorization: "Bearer {{ response['json']['token'] }}"
Content-Type: "application/json"
status_code: 201
register: launch

Guided Exercise 1 要点（lab: api-tower）

  1. lab api-tower start；Firefox 打开 https://tower.lab.example.com/api/（admin/redhat）浏览；访问 /api/v2/ping/（心跳可被外部程序用于健康检查）。
  2. 图形界面：找 Demo Job Template → 打开 launch 资源（GET 看需要哪些参数）→ 页底绿色 POST 按钮启动 → 回 Jobs 列表核对 job id。
  3. curl 版：sudo yum install perl-JSON-PP；curl -X GET --user admin:redhat ".../job_templates/?name=\"Demo Job Template\"" -k -s | json_pp 拿 ID → GET launch/ 看参数 → POST .../job_templates/5/launch/ → 记录返回 job id（如 28）→ Jobs 页核对。
  4. playbook 版：clone my_webservers_DEV（或 git pull）；cat tower_api.yml 看到 $ANSIBLE_VAULT 头（已用 ansible-vault、密码 redhat 加密）；ansible-vault view tower_api.yml 查看内容（启动 DEV ftpservers setup 的 uri POST）。
  5. 建/配 Vault Credential（密码 redhat）挂到 API usage Job Template → 启动该模板 → 观察它通过 API 启动了新的 DEV ftpservers setup 作业。
  6. lab api-tower finish 清理。

11.2 Interacting with APIs using Ansible Playbooks（用 playbook 与 API 交互）

uri 模块基础（考点）

  • 适用场景：服务在受管网络之外、无对应 Ansible 模块、或模块没暴露所需功能 → 用 uri 模块访问任意 HTTP/REST API。
  • 唯一必填参数 url；最常用参数 method：GET（默认，取实体）/ POST（让服务存储 body 中的实体）/ PUT（整体存/改）/ DELETE（删）/ PATCH（只带改动字段局部改）。
  • 自定义头：headers 字典（如 Cookie: type=TEST、Private-Token: xxx）。
  • 示例最小任务：- uri: url: http://www.example.com（默认 GET，检查可达与 200）。

发送信息到 API（考点：src/body/body_format）

  • 发送内容两个互斥参数：src（指向含请求体文件的路径）或 body（playbook 内 YAML 定义请求体）。
  • body_format：raw / json（REST API 用）/ form-urlencoded（传统表单页面用）。
  • 示例（表单登录）：
    - uri:
url: https://example.com/login.php
method: POST
body_format: form-urlencoded
body: { name: your_username, password: your_password, enter: "Sign in" }

处理 API 响应（考点）

  • status_code：期望的成功状态码（如 200/201/202/204）；不一致则任务失败（可用列表 [201, 202]）。
  • dest：把响应体保存成文件。
  • return_content: yes + register：把响应体放进结果字典（response.content）；结合 failed_when 校验内容（例：failed_when: "'SUCCESS' not in response.content"）。
  • JSON 解析：response 的 json 键已解析好——例：GitLab /api/v4/users 返回字典列表，loop: "{{ gitlab_api_result['json'] }}" 逐个取 item['username']。

HTTP 安全设置（考点）

  • 认证：url_username/url_password 支持 Digest/Basic/WSSE；Basic 自动认证失败时加 force_basic_auth: yes。
  • 私钥/TLS：client_cert（PEM 证书链文件）、client_key（若链文件不含密钥）；validate_certs: no 只在必须跳过证书校验时用（降低安全性，练习环境常用）。

数据准备与解析过滤器（考点）

  • urlencode：URL 只支持 US-ASCII 子集，拼 URL 前先编码（entity_name | urlencode）。
  • to_json / from_json：与 API 之间序列化/反序列化。
  • xml 模块（配过滤器）处理部分 API 返回的 XML。

Guided Exercise 2 要点（lab: api-interaction，围绕 Tower API 的“复制→加 Survey→启动→删除”闭环）

  1. lab api-interaction start；clone api-interaction.git；查看 inventory.yml：hosts=tower，vars 含 template_name: DEV ftpservers setup、copy_template_name: Exact copy of DEV ftpservers setup、tower_fqdn/user/password。
  2. 写 tower_copy_template.yml：
  • 复制模板：POST .../api/v2/job_templates/{{ template_name | urlencode }}/copy/，body {name: "{{ copy_template_name }}"}、body_format=json、status_code [201,202]、register: copy；注意：Tower API URL 必须以 / 结尾。
  • 启动副本：POST .../job_templates/{{ copy_template_name | urlencode }}/launch/，body 带 inventory: "{{ copy.json.inventory }}"（复用复制结果里返回的 inventory id）、body_format=json、status_code [201,202]。
  • 语法检查 ansible-playbook --syntax-check 后运行（play 打在 tower 主机）。
  1. 加 Survey：tower_add_survey.yml（向副本模板加 survey 并启用）；再给启动任务加 deployment_purpose: "Testing" 等 extra_vars，打 --tags with_variable 单独跑（survey 变量生效）。
  2. 清理 tower_template_cleanup.yml：DELETE .../job_templates/{{ copy_template_name | urlencode }}/，status_code 204 → 删除副本。
  3. git add . → commit “Tower API interaction” → push；lab api-interaction finish。

Lab 要点（lab: api-review，教材第 438~444 页 Performance Checklist）

  1. lab api-review start（建 api-review.git 仓库，内含待修复 playbook）。
  2. 修 inventory.yml 变量与 copy_template.yml：用 uri 模块把既有 Job Template New template 复制为 Review template（大小写敏感）；全部操作用 Tower 用户 simon；URL 形如 https://TOWER/api/v2/job_templates/{{ TEMPLATE_NAME | urlencode }}/copy/。
  3. 跑 copy 成功；改 template_cleanup.yml 用 DELETE 删掉原始 New template 并执行。
  4. 保存/提交/push；lab api-review grade 修正至通过；lab api-review finish。

SUMMARY（教材原话要点 4 条 → 考点归纳）

  • Tower 提供可浏览 REST API，易自动化运维并集成第三方产品（Ch10 已预告，本章落地）。
  • API 输出 JSON，人类阅读建议过 json_pp 等解析器。
  • 启动 Job Template 两段式：先 GET launch/ 拿所需参数，再 POST 同一 URI 真正启动。
  • playbook 用 uri 模块访问 Tower API 即可实现“作业启动作业”；敏感信息用 Vault（凭据/加密文件）保管。

命令速查表

| 场景 | 命令/写法 | | 浏览 API 入口 | curl -X GET https://tower/api/ -k；浏览器访问 /api/（可浏览、? 看文档） | | 美化 JSON | ... -s | json_pp（perl-JSON-PP） | | 按名找模板 | curl -X GET --user admin:redhat ".../job_templates/?name=\"Demo Job Template\"" -k -s | | 看 launch 参数 | curl -X GET .../api/v2/job_templates/5/launch/ -k -s | json_pp | | 启动作业 | curl -X POST .../api/v2/job_templates/5/launch/ -k -s（或 "Demo Job Template"/launch/） | | 查作业状态 | curl -X GET .../api/v2/jobs/<id>/ -k -s | json_pp | | 加密 playbook | ansible-vault encrypt api_demo.yml / ansible-vault view file | | Vault Credential | Credentials → “+” → TYPE=Vault → VAULT PASSWORD(+VAULT IDENTIFIER) | | Token | POST /api/v2/users/1/personal_tokens/ → headers Authorization: Bearer <token> | | uri 模块参数 | url/method/headers/src|body/body_format(raw|json|form-urlencoded)/status_code/dest/return_content/register | | 认证参数 | user/password + force_basic_auth；url_username/url_password；client_cert/client_key；validate_certs | | 过滤器 | urlencode、to_json、from_json、xml 模块 | | GE / Lab | lab api-tower / api-interaction / api-review start\|grade\|finish |

核心词汇表

英文中文速记
REST API表述性状态转移接口（HTTP 方法操作资源）
browsable API可浏览 API（Web 界面 + ? 文档）
v2Tower API 当前主版本（v1 将废弃）
json_ppJSON 美化输出（perl-JSON-PP）
pagination（next/previous）分页（next=null 是末页）
GET / POST / PUT / PATCH / DELETE读 / 建或触发 / 整体改 / 局部改 / 删
named URL / %20按名引用模板 / 空格转义（urlencode 过滤器）
launch endpoint模板的 launch 资源（GET 查参数 → POST 启动）
uri moduleAnsible 访问任意 HTTP API 的模块
body / src / body_format请求体（YAML 内联 / 文件）/ 格式 raw·json·form-urlencoded
status_code / return_content / register期望码 / 取回响应体 / 存结果变量
failed_when自定义失败条件（检查响应内容）
force_basic_auth强制 Basic 认证
validate_certs / client_certTLS 校验开关 / 客户端证书链
ansible-vault / Vault Credential加密文件 / Tower 解密凭据
OAuth2 / PATToken 认证 / 个人访问令牌（Bearer）
urlencode / to_json / from_jsonURL 编码 / JSON 序列化反序列化过滤器

本章自测

  1. Tower REST API 的价值与访问方式？为什么说“部分 UI 功能 API 不可达、v1 即将废弃”？
  2. API 输出是 JSON，肉眼难读——两个改善手段？（json_pp / 浏览器可浏览 API 与 ? 文档）
  3. 分页响应里 next/previous 字段怎么判断是否还有更多数据？
  4. “用 API 启动 Job Template”为什么是两段式？两个请求分别用什么方法、打哪个 URL？
  5. 名称含空格的模板怎么在 URL 里引用？在 playbook 里推荐用什么过滤器？
  6. playbook 里明文写 admin 密码有什么问题？两种 Vault 化手段？Tower 里怎么让作业能解密加密 playbook（Vault Credential 字段）？
  7. PAT 与 Application Token 区别？写出申请 PAT 与用它启动作业的 uri 任务要点（端点/方法/头）？
  8. uri 模块发请求体用哪两个互斥参数？REST API 与表单页分别配什么 body_format？
  9. 怎么“校验响应体内容”与“把响应保存成文件”？注册变量后 JSON 数据在哪取？
  10. GE2 用 API 完成了“复制→启动作业→加 Survey→删除”哪个端点是删？DELETE 的期望 status_code 是多少？SUMMARY 四条如何对应 Objectives 两条？