构建专属执行环境：awx-on-k3s自定义Ansible EE完整教程

构建专属执行环境：awx-on-k3s自定义Ansible EE完整教程

【免费下载链接】awx-on-k3sAn example implementation of AWX on single node K3s using AWX Operator, with easy-to-use simplified configuration with ownership of data and passwords.项目地址: https://gitcode.com/gh_mirrors/aw/awx-on-k3s

awx-on-k3s是基于K3s单节点部署AWX的开源项目，通过AWX Operator实现简化配置，让用户完全掌控数据和密码。本文将带你一步步构建专属的Ansible执行环境（EE），轻松定制满足特定需求的自动化运行环境。

为什么需要自定义Ansible EE？

Ansible执行环境（Execution Environment）是包含Ansible运行所需全部依赖的容器镜像，自定义EE能带来三大核心优势：

• 环境一致性：确保开发、测试和生产环境完全一致，消除"在我电脑上能运行"的问题
• 依赖隔离：不同项目的依赖互不干扰，避免版本冲突
• 安全合规：仅包含必要组件，减少攻击面，满足企业安全要求

awx-on-k3s项目提供了完整的EE构建框架，位于项目的builder/目录下，通过简单配置即可生成专属执行环境。

自定义Ansible EE的核心组件

在开始构建前，先了解awx-on-k3s中EE构建的核心文件结构：

1. 执行环境定义文件

builder/execution-environment.yml是EE构建的主配置文件，定义了基础镜像、依赖和构建步骤。关键配置项包括：

• 基础镜像：指定底层操作系统镜像，默认使用quay.io/centos/centos:stream9-minimal
• Python解释器：设置Python版本和路径，默认为Python 3.11
• 依赖管理：声明系统依赖、Python包和Ansible Galaxy集合的来源
• 构建步骤：添加自定义命令，如设置Python alternatives或配置Ansible

2. 依赖文件集合

EE的依赖通过三个文件管理，位于builder/dependencies/目录：

• system依赖：bindep.txt定义系统级依赖包
• Python依赖：requirements.txt声明Python模块，默认包含示例包example-pypi-package
• Ansible集合：requirements.yml指定Ansible Galaxy集合，默认包含community.general:7.0.0

从零开始自定义Ansible EE的步骤

准备工作：安装必要工具

在开始构建前，确保系统已安装：

• Docker或Podman
• Ansible Builder
• Git

克隆awx-on-k3s项目到本地：

git clone https://gitcode.com/gh_mirrors/aw/awx-on-k3s cd awx-on-k3s/builder

步骤1：修改执行环境定义

编辑builder/execution-environment.yml文件，根据需求调整配置：

1. 更换基础镜像：如需使用不同的基础镜像，修改images.base_image.name
2. 调整Python版本：修改dependencies.python_interpreter下的配置
3. 添加构建步骤：在additional_build_steps中添加自定义命令，如安装特定工具

例如，如需添加自定义CA证书，可在append_final部分添加：

append_final: - COPY custom-ca.crt /etc/pki/ca-trust/source/anchors/ - RUN update-ca-trust

步骤2：管理依赖项

根据项目需求更新依赖文件：

1. 系统依赖：编辑builder/dependencies/bindep.txt，添加所需系统包，格式为：

   openssh-clients [platform:rpm] git [platform:rpm]

2. Python依赖：修改builder/dependencies/requirements.txt，添加所需Python包：

   requests>=2.25.0 pywinrm>=0.4.3

3. Ansible集合：更新builder/dependencies/requirements.yml，添加所需集合：

   collections: - name: community.general version: 7.0.0 - name: ansible.posix version: 1.5.4

步骤3：构建执行环境镜像

完成配置后，使用Ansible Builder构建镜像：

ansible-builder build -t custom-awx-ee:latest

构建过程会自动：

1. 拉取基础镜像
2. 安装系统依赖
3. 设置Python环境
4. 安装Python包和Ansible集合
5. 执行自定义构建步骤
6. 生成最终镜像

步骤4：在AWX中使用自定义EE

构建完成后，有两种方式在awx-on-k3s中使用自定义EE：

1. 本地镜像：将镜像推送到项目中的私有仓库（registry/目录提供了本地仓库配置）
2. 更新AWX配置：修改base/awx.yaml中的执行环境设置，指定自定义镜像

高级定制技巧

添加自定义Ansible配置

项目提供了builder/files/ansible.cfg文件，可在此添加全局Ansible配置，如：

[defaults] timeout = 30 remote_user = ansible

配置会在构建过程中自动复制到EE中，位于~/.ansible.cfg。

多阶段构建优化

通过additional_build_steps的不同阶段（prepend_base、append_galaxy等），可以实现复杂的构建逻辑：

• prepend_base：基础镜像准备阶段
• append_galaxy：Galaxy集合安装后
• append_final：最终镜像打包前

版本控制与测试

建议为EE配置创建版本控制，可通过修改execution-environment.yml中的版本号实现：

version: 3

每次修改后，建议进行测试：

ansible-builder build --tag custom-awx-ee:v1.0 ansible-runner run --container-image custom-awx-ee:v1.0 demo-playbook.yml

故障排除与常见问题

构建失败怎么办？

1. 检查依赖文件格式是否正确，特别是YAML文件的缩进
2. 确认网络连接正常，能够访问镜像仓库和Galaxy
3. 查看构建日志，定位具体错误阶段

如何减小镜像体积？

1. 使用更小的基础镜像，如Alpine版本（需注意兼容性）
2. 在构建后期清理缓存和临时文件：

   append_final: - RUN microdnf clean all && rm -rf /var/cache/microdnf

自定义EE不生效？

1. 确认AWX已正确配置使用新镜像
2. 检查镜像是否已推送到AWX可访问的仓库
3. 查看AWX任务日志，确认是否有镜像拉取或运行错误

总结

通过awx-on-k3s项目提供的builder/框架，自定义Ansible执行环境变得简单高效。无论是添加特定依赖、配置企业安全策略，还是优化运行环境，都能通过修改几个关键文件轻松实现。

现在，你已经掌握了构建专属Ansible EE的完整流程，快去尝试定制满足自己需求的执行环境吧！如有更多高级需求，可参考项目tips/目录下的文档，获取更多专业技巧。

【免费下载链接】awx-on-k3sAn example implementation of AWX on single node K3s using AWX Operator, with easy-to-use simplified configuration with ownership of data and passwords.项目地址: https://gitcode.com/gh_mirrors/aw/awx-on-k3s