31、Ansible Galaxy：角色创建、发布与使用指南

Ansible Galaxy：角色创建、发布与使用指南

1. Ansible Galaxy 简介

Ansible Galaxy 为 Ansible 用户提供了一个共享和获取角色的平台。使用预定义的社区角色来部署应用，往往比自己编写角色更加简便。只需对应用安装有基本了解，快速浏览角色的 README 文件，就能在短时间内编写剧本并完成应用部署。

2. 发布角色

在了解如何下载角色后，我们可以通过创建角色为社区做出贡献。这里以安装 Docker 为例，将角色扩展为支持 Ubuntu 系统，并安装 Docker CE Edge 版本。

3. 创建 Docker 角色

• 初始化角色 ：在存储代码的目录下运行以下命令，创建角色所需的基本文件和目录结构。

$ ansible-galaxy init ansible-role-docker

• 变量设置 ：在 vars 文件夹中添加两个文件，分别用于不同操作系统的变量配置。
• vars/RedHat.yml ：

---
# vars file for ansible-role-docker
docker:
  gpg_key: "https://download.docker.com/linux/centos/gpg"
  repo_url: "https://download.docker.com/linux/centos/docker-ce.repo"
  repo_path: "/etc/yum.repos.d/docker-ce.repo"
  edge: "docker-ce-edge"
  packages:
    - "docker-ce"
    - "device-mapper-persistent-data"
    - "lvm2"
    - "python-setuptools"
    - "libselinux-python"
  pip:
    - "docker"

• vars/Debian.yml ：

---
# vars file for ansible-role-docker
docker:
  gpg_key: "https://download.docker.com/linux/ubuntu/gpg"
  repo: "deb [arch=amd64] https://download.docker.com/linux/{{ ansible_distribution | lower }} {{ ansible_distribution_release | lower }} edge"
  system_packages:
    - "apt-transport-https"
    - "ca-certificates"
    - "curl"
    - "software-properties-common"
    - "python3-pip"
  packages:
    - "docker-ce"
  pip:
    - "docker"

• 任务设置 ：由于针对两种不同的操作系统， tasks/main.yml 文件需要根据操作系统导入不同的任务文件。

---
# tasks file for ansible-role-docker
- name: include the operating system specific variables
  include_vars: "{{ ansible_os_family }}.yml"
- name: install the stack on centos
  import_tasks: install-redhat.yml
  when: ansible_os_family == 'RedHat'
- name: install the stack on ubuntu
  import_tasks: install-ubuntu.yml
  when: ansible_os_family == 'Debian'

• tasks/install-redhat.yml ：

---
# tasks file for ansible-role-docker
- name: add the gpg key for the docker repo
  rpm_key:
    key: "{{ docker.gpg_key }}"
    state: "present"
- name: add docker repo from the remote url
  get_url:
    url: "{{ docker.repo_url }}"
    dest: "{{ docker.repo_path }}"
    mode: "0644"
- name: install the docker packages
  yum:
    name: "{{ item }}"
    state: "installed"
    update_cache: "yes"
    enablerepo: "{{ docker.edge }}"
  with_items: "{{ docker.packages }}"
- name: install pip
  easy_install:
    name: pip
    state: latest
- name: install the python packages
  pip:
    name: "{{ item }}"
  with_items: "{{ docker.pip }}"
- name: put selinux into permissive mode
  selinux:
    policy: targeted
    state: permissive
- name: start docker and configure to start on boot
  service:
    name: "docker"
    state: "started"
    enabled: "yes"

• tasks/install-ubuntu.yml ：

---
# tasks file for ansible-role-docker
- name: install the system packages
  apt:
    name: "{{ item }}"
    state: "present"
    update_cache: "yes"
  with_items: "{{ docker.system_packages }}"
- name: add the apt keys from a key server
  apt_key:
    url: "{{ docker.gpg_key }}"
    state: present
- name: add the apt repo
  apt_repository:
    repo: "{{ docker.repo }}"
    state: present
- name: install the docker package
  apt:
    name: "{{ item }}"
    state: "present"
    update_cache: "yes"
    force: "yes"
  with_items: "{{ docker.packages }}"
- name: install the python packages
  pip:
    name: "{{ item }}"
  with_items: "{{ docker.pip }}"
- name: start docker and configure to start on boot
  service:
    name: "docker"
    state: "started"
    enabled: "yes"

4. 元数据设置

在 meta/main.yml 文件中添加角色的元数据，包括作者、描述、许可证、支持的 Ansible 版本等信息。

---
galaxy_info:
  author: "Russ McKendrick"
  description: "Role to install the Docker CE Edge release on either an Enterprise Linux or Ubuntu host"
  license: "license (BSD)"
  min_ansible_version: 2.4
  platforms:
    - name: EL
      versions:
      - 6
      - 7
    - name: Ubuntu
      versions:
      - bionic
      - artful
      - xenial
  galaxy_tags:
    - docker
dependencies: []

元数据各字段说明如下：
| 字段 | 说明 |
| ---- | ---- |
| author | 角色作者的姓名或昵称 |
| description | 角色的简要描述，用于命令行和网页搜索显示 |
| license | 角色的许可证，默认是 BSD |
| min_ansible_version | 角色支持的最低 Ansible 版本 |
| platforms | 支持的操作系统和版本列表 |
| galaxy_tags | 用于标识角色功能的标签 |

5. README 文件

完成角色的最后一部分是 README.md 文件，它包含在 Ansible Galaxy 网站上显示的信息。以下是一个示例：

Ansible Docker Role
=========
This role installs the current Edge build Docker CE using the official
repo, for more information on Docker CE see the official site at
[https://www.docker.com/community-edition](https://www.docker.com/community-edition).

Requirements
------------
Apart from requiring root access via `become: yes` this role has no special
requirements.

Role Variables
--------------
All of the variables can be found in the `vars` folder.

Dependencies
------------
None.

Example Playbook
----------------
An example playbook can be found below;
```yaml
- hosts: docker
  gather_facts: true
  become: yes
  become_method: sudo
  roles:
    - russmckendrick.docker

License

BSD

Author Information

This role is published by Russ McKendrick .

#### 6. 提交代码并发布
- **创建 GitHub 仓库**：登录 GitHub，点击右上角的 `+` 图标，选择 `New repository`，仓库名称应遵循 `ansible-role-your-role-name` 的格式。
- **本地初始化 Git 仓库并推送代码**：在角色所在的目录下运行以下命令。
```bash
$ git init
$ git add -A .
$ git commit -m "first commit"
$ git remote add origin git@github.com:russmckendrick/ansible-role-docker.git
$ git push -u origin master

• 导入角色到 Ansible Galaxy ：使用 GitHub 凭证登录 Ansible Galaxy，点击 My Content ，若未看到仓库列表，点击搜索框旁边的刷新图标。看到仓库后，点击角色旁边的开关导入角色。

7. 测试角色

• 创建所需文件 ：运行以下命令创建测试所需的文件和目录。

$ mkdir docker
$ cd docker
$ touch production requirements.yml site.yml Vagrantfile

• 配置文件内容 ：
• production （库存文件）：

centos ansible_host=10.20.30.10.nip.io
ubuntu ansible_host=10.20.30.20.nip.io
ansible_python_interpreter=/usr/bin/python3
[docker]
centos
ubuntu
[docker:vars]
ansible_connection=ssh
ansible_user=vagrant
ansible_private_key_file=~/.ssh/id_rsa
host_key_checking=False

• requirements.yml ：

- src: "russmckendrick.docker"

• site.yml （剧本文件）：

---
- hosts: docker
  gather_facts: true
  become: yes
  become_method: sudo
  roles:
    - russmckendrick.docker

• Vagrantfile ：

# -*- mode: ruby -*-
# vi: set ft=ruby :
API_VERSION = "2"
DOMAIN = "nip.io"
PRIVATE_KEY = "~/.ssh/id_rsa"
PUBLIC_KEY = '~/.ssh/id_rsa.pub'
CENTOS_IP = '10.20.30.10'
CENTOS_BOX = 'centos/7'
UBUNTU_IP = '10.20.30.20'
UBUNTU_BOX = 'generic/ubuntu1804'
Vagrant.configure(API_VERSION) do |config|
  config.vm.define "centos" do |centos|
      centos.vm.box = CENTOS_BOX
      centos.vm.network "private_network", ip: CENTOS_IP
      centos.vm.host_name = CENTOS_IP + '.' + DOMAIN
      centos.ssh.insert_key = false
      centos.ssh.private_key_path = [PRIVATE_KEY,
"~/.vagrant.d/insecure_private_key"]
      centos.vm.provision "file", source: PUBLIC_KEY, destination:
"~/.ssh/authorized_keys"
      centos.vm.provider "virtualbox" do |v|
        v.memory = "2024"
        v.cpus = "2"
      end
      centos.vm.provider "vmware_fusion" do |v|
        v.vmx["memsize"] = "2024"
        v.vmx["numvcpus"] = "2"
      end
  end
  config.vm.define "ubuntu" do |ubuntu|
      ubuntu.vm.box = UBUNTU_BOX
      ubuntu.vm.network "private_network", ip: UBUNTU_IP
      ubuntu.vm.host_name = UBUNTU_IP + '.' + DOMAIN
      ubuntu.ssh.insert_key = false
      ubuntu.ssh.private_key_path = [PRIVATE_KEY,
"~/.vagrant.d/insecure_private_key"]
      ubuntu.vm.provision "file", source: PUBLIC_KEY, destination:
"~/.ssh/authorized_keys"
      ubuntu.vm.provider "virtualbox" do |v|
        v.memory = "2024"
        v.cpus = "2"
      end
      ubuntu.vm.provider "vmware_fusion" do |v|
        v.vmx["memsize"] = "2024"
        v.vmx["numvcpus"] = "2"
      end
  end
end

• 下载角色并测试 ：

$ ansible-galaxy install -r requirements.yml
$ vagrant up
$ ansible-playbook -i production site.yml

8. Ansible Galaxy 命令

• 登录 ：可以使用以下命令从命令行登录 Ansible Galaxy。

$ ansible-galaxy login

若启用了 GitHub 双因素认证，需要使用个人访问令牌登录。

$ ansible-galaxy login --github-token 0aa7c253044609b98425865wbf6z679a94613bae89

• 导入 ：登录后，若对角色进行了修改，可以使用以下命令将更改导入到 Ansible Galaxy。

$ ansible-galaxy import russmckendrick ansible-role-docker

• 搜索 ：使用以下命令搜索角色。

$ ansible-galaxy search docker
$ ansible-galaxy search --author=russmckendrick docker

• 信息查看 ：使用以下命令查看角色的详细信息。

$ ansible-galaxy info russmckendrick.docker

9. 总结

Ansible Galaxy 为 Ansible 用户提供了一个有价值的社区服务平台，方便用户共享角色和为社区做出贡献。但在生产环境中使用 Ansible Galaxy 中的角色时，要仔细检查代码并阅读问题跟踪器，因为很多角色需要提升权限才能执行任务。

流程图

graph LR
    A[开始] --> B[创建 Docker 角色]
    B --> C[设置变量]
    C --> D[设置任务]
    D --> E[设置元数据]
    E --> F[编写 README 文件]
    F --> G[提交代码到 GitHub]
    G --> H[导入角色到 Ansible Galaxy]
    H --> I[测试角色]
    I --> J[使用 Ansible Galaxy 命令]
    J --> K[结束]

通过以上步骤，你可以在 Ansible Galaxy 上创建、发布和测试自己的角色，并使用相关命令进行管理。希望这些内容对你有所帮助！

Ansible Galaxy：角色创建、发布与使用指南（续）

10. 各步骤注意事项

在整个使用 Ansible Galaxy 创建、发布和测试角色的过程中，有一些关键的注意事项需要牢记，以下为你详细说明：

步骤	注意事项
创建 GitHub 仓库	仓库名称务必遵循 ansible-role-your-role-name 的格式，因为 Ansible Galaxy 上角色的名称依赖于 ansible-role 之后的部分，若格式错误可能导致角色无法正常导入或识别。
本地初始化 Git 仓库并推送代码	在执行 git push -u origin master 时，要确保替换成自己的仓库 URL，若 URL 错误，代码将无法正确推送到 GitHub 仓库。若推送代码遇到问题，可参考 GitHub 提供的关于设置 Git（https://help.github.com/articles/set-up-git/）和推送首个文件（https://help.github.com/articles/create-a-repo/）的优秀文档。
导入角色到 Ansible Galaxy	使用 GitHub 凭证登录时，若 GitHub 账户启用了双因素认证，普通的用户名和密码登录方式将失效，需要生成个人访问令牌并使用 ansible-galaxy login --github-token 命令登录。个人访问令牌具有较高权限，要妥善保存，建议定期更换。
测试角色	在创建 production 库存文件时，要确保 ansible_host 的 IP 地址和域名配置正确，以及 ansible_python_interpreter 指向正确的 Python 解释器路径，否则可能导致 Ansible 无法正常连接和执行任务。

11. 常见问题及解决办法

在使用 Ansible Galaxy 的过程中，可能会遇到一些常见问题，下面为你列举并提供相应的解决办法：

问题	现象	解决办法
登录失败	使用 ansible-galaxy login 输入 GitHub 用户名和密码后提示认证失败	若 GitHub 账户启用了双因素认证，需生成个人访问令牌，然后使用 ansible-galaxy login --github-token <token> 命令登录。生成个人访问令牌的地址为：https://github.com/settings/tokens/。
角色导入失败	在 Ansible Galaxy 中点击导入角色开关后，角色未成功导入	检查 GitHub 仓库是否为公开仓库，因为 Ansible Galaxy 需要从公开仓库下载角色代码。同时，确保仓库名称遵循 ansible-role-your-role-name 的格式。
测试角色时任务执行失败	运行 ansible-playbook -i production site.yml 时出现错误	检查 production 库存文件中的主机配置是否正确，包括 IP 地址、用户名、私钥路径等。检查角色代码中的变量和任务配置是否与目标主机的操作系统和环境匹配。

12. 进阶使用建议

• 角色版本管理 ：在 GitHub 仓库中使用标签（tags）来管理角色的版本。例如，当角色有重大更新时，创建一个新的标签，如 v1.1 。这样在 Ansible 的 requirements.yml 文件中可以指定使用特定版本的角色，提高稳定性。示例如下：

- src: "russmckendrick.docker"
  version: "v1.1"

• 角色依赖管理 ：若角色依赖其他角色，可以在 meta/main.yml 文件的 dependencies 字段中添加依赖信息。例如：

galaxy_info:
  # 其他元数据信息
dependencies:
  - name: another-role
    src: "author.another-role"
    version: "v1.0"

• 持续集成与持续部署（CI/CD） ：结合 CI/CD 工具（如 Jenkins、GitLab CI/CD 等），实现角色代码更新后自动测试和部署。例如，在 GitHub 仓库中配置 GitLab CI/CD，当有新代码推送到仓库时，自动运行测试脚本，确保角色的质量。

13. 与其他工具的集成

Ansible Galaxy 可以与多种工具集成，进一步提升工作效率，以下是一些常见的集成场景：

• 与 Vagrant 集成 ：如前面测试角色时所示，使用 Vagrant 创建虚拟环境，配合 Ansible 进行自动化部署。Vagrantfile 可以定义虚拟主机的配置，Ansible 则负责在这些主机上安装和配置软件。
• 与 Docker 集成 ：可以使用 Ansible Galaxy 中的角色来管理 Docker 容器的部署和配置。例如，使用角色在多台主机上安装 Docker，并创建和管理 Docker 容器。
• 与 Jenkins 集成 ：将 Ansible 任务集成到 Jenkins 的构建流程中，实现自动化部署。例如，在 Jenkins 中配置一个任务，当代码更新时，自动拉取最新代码，使用 Ansible 部署到目标主机。

14. 社区贡献与交流

Ansible Galaxy 是一个活跃的社区，积极参与社区贡献和交流可以提升自己的技术水平，同时也能为社区做出贡献：

• 参与讨论 ：在 Ansible Galaxy 的官方论坛或 GitHub 仓库的 Issues 页面参与讨论，分享自己的经验和遇到的问题，与其他开发者交流。
• 提交代码 ：若发现角色中的 bug 或有改进的建议，可以提交 Pull Request 到角色的 GitHub 仓库，为角色的改进做出贡献。
• 分享角色 ：将自己创建的有用角色发布到 Ansible Galaxy 上，供其他开发者使用，促进社区的发展。

流程图

graph LR
    A[注意事项] --> B[常见问题解决]
    B --> C[进阶使用]
    C --> D[工具集成]
    D --> E[社区贡献交流]

通过以上对 Ansible Galaxy 各个方面的深入了解，你不仅能够熟练地创建、发布和测试自己的角色，还能在使用过程中避免常见问题，进行进阶操作，并与社区进行良好的互动。希望这些内容能帮助你更好地利用 Ansible Galaxy 提升工作效率和技术能力。