如何在Ansible的argument_spec中正确使用加密变量？

我在使用argument_specs.yml优化Ansible角色时，遇到了ansible-vault加密变量的兼容性问题。运行包含该角色的剧本时，抛出如下错误：

{
  "argument_errors": [
    "Failed to convert \"password\": Unknown parameter type: <class 'ansible.parsing.yaml.objects.AnsibleVaultEncryptedUnicode'>",
    ...
  ],
  "argument_spec_data": {
    "myApp": {
      "description": "Some description",
      "options": {
        "some_var": "foo",
        "database": {
          "description": "database credentials",
          "options": {
            "password": {
              "description": "DB password",
              "no_log": true,
              "required": true,
              "type": "str"
            },
            "url": {
              "description": "DB URL",
              "required": true,
              "type": "str"
            },
            "username": {
              "description": "DB user",
              "required": true,
              "type": "str"
            }
          },
          "required": true,
          "type": "dict"
        }
      }
    }
  }
}

变量password的值已通过ansible-vault加密，我在Ansible官方文档中未找到相关说明。环境信息：

• Ansible版本8（核心版本2.15）
• Python版本3.10
• Jinja版本3.1.2

复现问题的角色代码如下：

role/tasks/main.yml:

---
# copy template to home dir with credentials
- name: Copy Credentials
  ansible.builtin.template:
    src: credentials.txt.j2
    dest: /opt/credentials.txt
  become: true

role/meta/argument_specs.yml:

---
argument_specs:
  main:
    short_description: "Some description"
    options:
      myApp:
        type: dict
        required: true
        description: "Some description"
        options:
          version:
            type: str
            required: true
            description: "the version"
          database:
            type: "dict"
            required: true
            description: database credentials
            options:
              url:
                type: "str"
                required: true
                description: database URL
              username:
                type: "str"
                required: true
                description: Username to access database
              password:
                type: "str"
                required: true
                description: Password to access database

role/templates/credentials.txt.j2:

user: {{ myApp.database.username }}
pass: {{ myApp.database.password }}

Ansible 2.15（对应Ansible 8）的参数校验机制会严格检查变量类型：通过ansible-vault加密的值，其类型为AnsibleVaultEncryptedUnicode，而非原生的Python字符串类型str。当你在argument_specs.yml中为password指定type: str时，校验逻辑无法识别这个加密类型，因此抛出类型转换错误。

将password参数的类型从str改为raw即可解决问题。raw类型会接受任何类型的输入，包括Ansible的加密类型，并且在实际使用时会自动解密为字符串，完全满足你的需求。

修改后的role/meta/argument_specs.yml中password部分如下：

password:
  type: "raw"  # 替换原来的type: str
  required: true
  description: Password to access database
  no_log: true  # 建议添加，避免密码在日志中泄露

这样修改后，参数校验会通过，加密的密码也能正常在模板中解密使用。

内容的提问来源于stack exchange，提问作者Human